home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / s / sas_utilities / sasutilities08.dms / in.adf / cHECKGUIDe(cLi) / CheckGuide.doc next >
Encoding:
Text File  |  1992-12-21  |  3.4 KB  |  95 lines
  1.  
  2.           CheckGuide 1.0 -- Checks AmigaGuide files for common errors
  3.  
  4.              by Eddy Carroll, September 1994. Freely distributable.
  5.  
  6. INTRODUCTION
  7.  
  8.     If you've ever tried creating even a modestly sized AmigaGuide file
  9.     by hand, you'll have discovered that it can be quite difficult to
  10.     keep track of all the various links and cross references. As your
  11.     help file gets larger, it gets increasingly harder to ensure that
  12.     you have remembered to reference all the nodes in the file from at
  13.     least one place, and haven't left any unresolved links.
  14.  
  15.     CheckGuide is a simple utility that can detect several common errors
  16.     in AmigaGuide files. The errors it can detect are:
  17.  
  18.      o  Extra plain text between an @ENDNODE and @NODE (AmigaGuide won't
  19.         allow such text to ever be displayed)
  20.  
  21.      o  Nodes that are defined but not referenced from any other node.
  22.         Unless your program directly instructs AmigaGuide to access such
  23.         nodes, the user won't easily be able to access them.
  24.  
  25.      o  Links to help nodes that aren't defined within the file.
  26.  
  27.      o  Open braces with no preceding @ character (usually a simple typo).
  28.  
  29.      o  @{" Button "} constructs with no LINK command (an easy mistake to
  30.         make if you're entering a lot of them).
  31.  
  32.     All of these options can be selectively enabled or disabled.
  33.  
  34.  
  35. USAGE
  36.  
  37.     The command template looks like this:
  38.  
  39.         CheckGuide filename.guide [Options]
  40.  
  41.     Filename.guide is the AmigaGuide file you wish to check. The .guide
  42.     suffix is optional; CheckGuide will add it if necessary. The valid
  43.     options are:
  44.  
  45.         EXTRATEXT  Check for extra text between @ENDNODE and @NODE
  46.             NODES  Check for nodes that are not referenced anywhere
  47.              REFS  Check for references to non-existant nodes
  48.            BRACES  Check for braces that aren't preceded by @
  49.              LINK  Check that every node reference includes LINK keyword
  50.               ALL  Perform all the above checks (default)
  51.           VERBOSE  Display lines with errors for EXTRATEXT and BRACES
  52.  
  53.     In addition, each option can optionally be prefixed by the word NO.
  54.     Although ALL is the default, specifying any of the options on its
  55.     own causes all other options to be disabled. You can selectively
  56.     disable just a single option by specifying its negative version.
  57.     For example:
  58.  
  59.         CheckGuide file NOBRACES
  60.  
  61.     will perform all checks except for the BRACES check (useful if the
  62.     Guide file includes some snippets of C source, where the braces are
  63.     actually legitimate). Another example:
  64.  
  65.         CheckGuide file NODES REFS
  66.  
  67.     will run only the Nodes and Refs checks.
  68.  
  69.     The VERBOSE option is useful if your file doesn't have too many errors;
  70.     it causes any problem lines to be printed to the screen, so you can
  71.     immediately check if there's a real fault or not.
  72.  
  73.  
  74. FUTURE
  75.  
  76.     This was really only written as a quick hack, since I had a rather large
  77.     AmigaGuide file I needed to check. It's not great, but it's better
  78.     than nothing. Source is included in case you think of anything else
  79.     you'd like to do; if you make any useful changes, I'd appreciate you
  80.     sending me a copy of them.
  81.  
  82.  
  83. DISTRIBUTION
  84.  
  85.     This code is freely distributable. It may be used for any commercial or
  86.     non-commercial application whatsoever.
  87.  
  88.  
  89. AUTHOR
  90.  
  91.     Eddy Carroll can be reached at either of the following addresses:
  92.  
  93.         ecarroll@maths.tcd.ie
  94.         ecarroll@cix.compulink.co.uk
  95.